home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / system / filesyst / dosfs / readme.dos < prev    next >
Text File  |  1993-03-24  |  12KB  |  335 lines
  1. MS-DOS FS, ALPHA test version 11
  2. ================================
  3.  
  4.  
  5. *****  This is an ALPHA test version. It might contain bugs that    *****
  6. *****  will make an MS-DOS FS unusable. Use it only on copies of    *****
  7. *****  your disks. Never work on original data with it !            *****
  8.  
  9.  
  10. FILES
  11. =====
  12.  
  13.     README        This file.
  14.     CHANGES        Change history.
  15.     Makefile        Makefile for fromdos and rename.
  16.     dosfs.patch        Patch from alpha.8 to alpha.11
  17.     dosfs.tar       MS-DOS FS for the 0.99pl7 kernel.
  18.     fromdos.c        CRLF->NL / NL->CRLF converter.
  19.     test.pl        Regression test script in Perl.
  20.     rename.c        Interface to the rename system call. Used by test.pl
  21.     smount.c        Very simple mount program.
  22.     fsperf.c        File system performance test.
  23.  
  24.  
  25. INSTALLATION
  26. ============
  27.  
  28. This update of the MS-DOS FS can only be added to a 0.99pl7 kernel. You can
  29. either overwrite the old sources by extracting dosfs.tar or patch the
  30. sources from dosfs.patch. Patching is preferred, but many people find it
  31. more convenient to replace the sources from a TAR archive.
  32.  
  33. Kernel versions later than 0.99pl7 may or may not work with this
  34. source/patch. Please use 0.10 for 0.99pl6 kernels.
  35.  
  36. Step 1: Kernel
  37.  
  38.     Update the kernel sources if needed and delete all old *.o files that
  39.     may be in fs/msdos. Then run make and boot the resulting image.
  40.  
  41. Step 2: Basic utilities
  42.  
  43.     Run make to compile smount.c, fromdos.c, fsperf.c. Move the resulting
  44.     executables to an appropriate place and create a link from 'todos'
  45.     to 'fromdos'.
  46.  
  47. Now you're ready to use the MS-DOS FS. If you have Perl, you should
  48. run the regression test now. (See below.)
  49.  
  50.  
  51. MOUNTING
  52. ========
  53.  
  54. An MS-DOS FS is mounted by specifying the FS type "msdos" with the
  55. -t option:
  56.  
  57.     mount -t msdos /dev/whatever /wherever
  58.  
  59. The following mount options are recognized:
  60.  
  61.     conv=binary|text|auto        (default is "binary")
  62.     check=relaxed|normal|strict        (default is "normal")
  63.     uid=<number>            (default is current euid)
  64.     gid=<number>            (default is current egid)
  65.     umask=<number>            (default is current umask)
  66.     debug                (default is off)
  67.     fat=<number>            (default is auto-detection)
  68.  
  69. The MS-DOS FS can perform CRLF<-->NL (MS-DOS text format to UNIX text
  70. format) conversion in the kernel. The following conversion modes are
  71. available:
  72.  
  73.   binary    no translation is performed.
  74.   text        CRLF<-->NL translation is performed on all files.
  75.   auto        CRLF<-->NL translation is performed on all files that
  76.         don't have a "well-known binary" extension. The list
  77.         of known extensions can be found at the beginning of
  78.         fs/msdos/misc.c
  79.  
  80. The conversion mode is chosen with the conv=<mode> mount option, e.g.
  81. mount -t msdos -o conv=auto ...
  82.  
  83. Programs that do computed lseeks won't like in-kernel text conversion.
  84.  
  85. For FS' mounted in binary mode, a conversion tool (fromdos/todos) is
  86. provided.
  87.  
  88. The kernel displays format information at mount time. Please include a
  89. verbatim copy of those numbers in your bug report if the FS should
  90. refuse to mount a valid MS-DOS disk.
  91.  
  92. When translating a name to MS-DOS conventions, three different levels
  93. of pickyness can be chosen:
  94.  
  95.   relaxed    Upper and lower case are accepted and equivalent, long
  96.         name parts are truncated (e.g. verlongname.foobar
  97.         becomes verylong.foo), leading and embedded spaces are
  98.         accepted in each name part (name and extension).
  99.   normal    Like "relaxed", but many special characters (*, ?, <,
  100.         spaces, etc.) are rejected.
  101.   strict    Like "normal", but names may not contain long parts and
  102.         special characters that are sometimes used on Linux,
  103.         but are not accepted by MS-DOS are rejected. (+, =,
  104.         spaces, etc.)
  105.  
  106. The check is chosen by specifying the check=<level> mount option,
  107. e.g. mount -t msdos -o check=strict ...
  108. Default is "normal".
  109.  
  110. The options uid=..., gid=... and umask=... determine the ownership and
  111. permissions of files. All files are implicitly chowned to the specified
  112. uid/gid and the bits in umask are removed from file permissions before
  113. they become visible to user programs. The root of the value of umask
  114. defaults to octal.
  115.  
  116. The fat option overrides the automatic FAT type detection. Only the
  117. values 12 and 16 are accepted.
  118.  
  119. The MS-DOS FS prints a version string and a list of file system para-
  120. meters if the option debug is set or if the parameters appear to be
  121. inconsistent.
  122.  
  123. If the MS-DOS FS detects an inconsistency, it reports an error and sets
  124. the file system read-only. The file system can be made writeable again
  125. by remounting it, e.g. mount -o remount,rw /dev/foo /bar
  126.  
  127. If the MS-DOS FS and your mount program don't agree on mount option
  128. processing, smount should be used in order to pass mount options. It's
  129. a very simple interface to the mount system call, that doesn't know
  130. about /etc/fstab and doesn't update /etc/mtab.
  131.  
  132.  
  133. REGRESSION TEST
  134. ===============
  135.  
  136. A regression test script is included that can be used to verify basic
  137. file system operation. It currently only analyzes the static behaviour
  138. of the FS. No attempt is made to detect race conditions.
  139.  
  140. To perform the regression test, do the following:
  141.  
  142. Step 1: rename utility
  143.  
  144.     Because at least some versions of Perl on Linux implement rename by
  145.     using link and unlink, a separate C program is used as an interface
  146.     to the rename system call. Run  make rename  to build it. The rename
  147.     executable must be in the directory from which test.pl is started.
  148.  
  149. Step 2: Test location
  150.  
  151.     Insert an empty MS-DOS floppy disk into /dev/fd0 or /dev/fd1. If you
  152.     don't have an empty MS-DOS floppy, you can create one with fdformat
  153.     and mformat. Mount the floppy as MS-DOS FS, e.g.
  154.     mount -t msdos /dev/fd0 /fd
  155.  
  156. Step 3: Running the script
  157.  
  158.     Run test.pl with the mount point and the name check mode as
  159.     arguments, e.g.
  160.     ./test.pl /fd normal
  161.     The regression test only works on an MS-DOS FS, because it tests
  162.     special behaviour of that FS type.
  163.  
  164. Step 4: Checking what's left
  165.  
  166.     The test should not leave any directories or files on the test disk.
  167.     The number of free blocks that is reported by df should also be the
  168.     same as before the test. Finally, you should be able to umount the
  169.     MS-DOS disk.
  170.  
  171. If any of the above fails, please don't hesitate to report it to
  172. almesber@bernina.ethz.ch
  173.  
  174. Contribution of new tests that verify yet untested parts of the code or
  175. tests that exhibit bugs will be thankfully accepted.
  176.  
  177.  
  178. ACCESS PERMISSIONS
  179. ==================
  180.  
  181. All files in an MS-DOS FS are owned by the real uid/real gid that are
  182. in effect for the mount system call. File modes are 0777 (0666 if the
  183. file system is mounted noexec) minus the current umask at mount time.
  184.  
  185. Read-only and hidden attributes are translated into appropriate mode
  186. settings. If file modes are changed, an attempt is made to find
  187. sensible attributes based on the mode bits of the owner.
  188.  
  189.  
  190. FROMDOS/TODOS
  191. =============
  192.  
  193. fromdos removes all CRs from a file and truncates it at the first ^Z.
  194. todos converts NLs to CRLFs.
  195.  
  196. Both tools are either invoked as filters, e.g. fromdos <foo.doc | more
  197. or with one or more file names. Those files are converted in place,
  198. e.g. todos foo.c bar.c gna.c
  199.  
  200.  
  201. FSPERF
  202. ======
  203.  
  204. fsperf tests the performance of common file system operations. Unlike
  205. common disk benchmarks, fsperf tries to ignore the time spent moving
  206. data from or to the disk but keeps as much data as possible in the
  207. buffer cache.
  208.  
  209. In order to get consistent results, the update process should be killed
  210. before running fsperf.
  211.  
  212. fsperf is invoked as follows:
  213.  
  214.   fsperf path
  215.  
  216. where path is an unused name in the top-level directory of a file
  217. system. WARNING: fsperf tries to delete any existing file or directory
  218. with that name !
  219.  
  220. fsperf repeats each set of operations ten times. This can be changed
  221. with the -i option, e.g. fsperf -i 5 /mnt/perf
  222.  
  223. The size of files created to measure sequential read and write
  224. performance should be considerably lower than the total amount of
  225. physical memory. The file size defaults to 4 MB and can be changed
  226. with the -m option, e.g. fsperf -m 2 /mnt/perf  -m 0 disables
  227. sequential file access tests.
  228.  
  229. The number of directory entries created to measure directory operation
  230. performance defaults to 100. This can be changed with the -e option,
  231. e.g. fsp